/**
 * 该模块提供键-值映射接口。
 * License: BSD
 * Authors: Lucifer (786325481@QQ.com)
 * Copyright: Copyright (C) 2008 Lucifer. All rights reserved.
 */
module system.collections.IMap;

import system.collections.IEnumerable;
import system.collections.IEnumerator;
import system.collections.ICollection;
import system.collections.Pair;

/**
 * 表示键-值对泛型集合应实现的映射接口。
 * Params:
 * 		TKey = 映射中键的类型。
 *		TValue = 映射中值的类型。
 * Comments:
 *		IMap(TKey, TValue) 接口是键-值对泛型集合的基接口。
 *		每个元素都是一个存储在 Pair(TKey, TValue) 对象中的键-值对。
 *		每一对都必须有唯一的键。
 *		IMap(TKey, TValue) 接口允许对所包含的键和值进行枚举，但这并不意味着任何特定的排序顺序。
 *
 *		Note:
 *		由于键可以被继承重写，因此使用 opEquals 方法进行的比较并不能保证其绝对唯一性。
 *
 *		<b>给实现者的说明：</b>
 *		实现类必须有一种方式来对键进行比较。
 *
 */
public interface IMap(TKey, TValue) : IEnumerable!(Pair!(TKey, TValue)), ICollection!(Pair!(TKey, TValue))
{
	/**
	 * 在 IMap(TKey, TValue) 中添加一个带有所提供的键和值的元素。
	 * Params:
	 *		key = 用作要添加的元素的键的对象。
	 *		value = 用作要添加的元素的值的对象。
	 */
	void add(TKey key, TValue value);

	/**
	 * 确定 IMap(TKey, TValue) 是否包含具有指定键的元素。
	 * Params:
	 *		key = 要在 IMap(TKey, TValue) 中定位的键。
	 * Returns:
	 *		如果 IMap(TKey, TValue) 包含带有该键的元素，则为 true；否则，为 false。
	 * Comments:
	 *		在如何确定对象是否等同方面，这些实现可能存在差异；
	 *		例如，ArrayList(T) 类使用 DefaultComparer(T) ，
	 *		而 HashMap(TKey, TValue) 类允许用户指定使用 IComparer(T) 实现来比较键。
	 *		实现在是否允许 key 为 null 方面有所不同。
	 */
	bool containsKey(TKey key);

    /**
     * 测试指定的值是否存在于此 Map 中。
     */
	bool containsValue(TValue value);

	/**
	 * 根据指定的键移除 IMap(TKey, TValue) 中指定的键-值对。
	 */
	bool remove(TKey key);

	/**
	 * 获取与指定的键相关联的值。
	 * Params:
	 *		key = 要获取其值的键。
	 *		value = 当此方法返回时，如果找到指定键，则返回与该键相关联的值；
	 *				 否则，将返回 value 参数的类型的默认值。该参数未经初始化即被传递。
	 *	Returns:
	 *		如果实现 IMap(TKey, TValue) 的对象包含具有指定键的元素，则为 true；否则，为 false。
	 */
	bool tryGetValue(TKey key, out TValue value);

	/**
	 * 获取包含 IMap(TKey, TValue) 的键的 ICollection(TKey)。
	 * Comments:
	 *		未指定返回的 ICollection(TKey) 中的键的顺序，但可以保证它与由 values 属性返回的 ICollection(TValue) 中的相应值具有相同的顺序。
	 */
	ICollection!(TKey) keys();

	/**
	 * 获取包含 IMap(TKey, TValue) 中的值的 ICollection(TValue)。
	 * Comments:
	 *		未指定返回的 ICollection(TValue) 中的值的顺序，但可以保证它与由 Keys 属性返回的 ICollection(TKey) 中的相应键具有相同的顺序。
	 */
	ICollection!(TValue) values();

	/**
	 * D 语言索引器重载实现。
	 */

	/**
	 * 获取具有指定键的元素。
	 */
	TValue opIndex(TKey key);

	/**
	 * 设置具有指定键的元素。
	 */
	void opIndexAssign(TValue value, TKey key);
}
